API REFERENCE

Authentication Docs

Getting Started

SAP Concur's new Oauth2 framework is a very simple way to implement a Unified Token Authentication mechanism within your application. Here is a four step guide to helping you get up to speed and making calls to SAP Concur's API.

Note: The Pre-2017 Authorization (Deprecated) documentation can be found here

• Obtain Your Application clientID and clientSecret
• Obtaining an Access Token
• Calling an API with the Access Token
• Access Token Expiry and Obtaining a Fresh One

Obtain clientID and clientSecret

Before you can obtain an accessToken, you need to register an application with SAP Concur. You can do this by contacting your Partner Enablement Manager or Partner Account Manager. Once you have registered an application, you will receive a clientId, clientSecret and geolocation. The clientId is a unique UUID4 identifier for your application, and the clientSecret is your application's password. You will be using this credential to obtain tokens either for the application itself, or on behalf of a user. The geolocation is your default base URI for initiating all new connections.

Obtaining an Access Token

In order for an application to call a SAP Concur API, you need to obtain an accessToken on behalf of either a User, Company or Application. There are multiple ways of obtaining an accessToken through the various grants (Password, Authorization, Client Credentials, One-time Password) .

This section provides a quick start guide for generating an access token. If you are developing an application to be certified for the App Center or as a TripLink supplier, please refer to the certification documentation for the grant types your application must support.

For simplicity, we will use the Password grant flow as an example. The Password grant flow is used when you need to authenticate a user, using its username and password. This is typically reserved from SAP Concur applications (i.e. where the user's credentials will be captured and stored) but is used here for demonstration purposes.

When making the call, you will use your app's geolocation as the base URI followed by the endpoint. For example, if your geolocation is https://us.api.concursolutions.com, you will call https://us.api.concursolutions.com/oauth2/v0/token.

The first time you request for an accessToken a refreshToken is also returned. There are certain conditions where a refreshToken is not returned. This is used to get a new accessToken when one has expired. (see below for more info)

Example shell script using cURL to obtain an accessToken:

oauth2_base=https://us.api.concursolutions.com/oauth2
username=<concur_username> eg. john.doe@gmail.com
password=<password> eg. password1
client_id=<clientId> eg. e01f725d-b4ce-4ce3-a664-b670cb5876cb0
client_secret=<clientSecret> eg. 35c3bd92-fcb8-405e-a886-47ff3fba5664
curl -X POST -H 'concur-correlationid: nameofapp' "$oauth2_base/v0/token" --data "username=$username&password=$password&grant_type=password&client_secret=$client_secret&client_id=$client_id"

Full docs: https://developer.concur.com/slate-ui/build/api-reference.html#password-grant

Store the token and geolocation.

Calling an API with Access Token

Once you have the accessToken, you need to supply this in an Authorization header in the form of Authorization: Bearer <accessToken> when making a HTTPS call. The accessToken is a large string that looks something like this:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJhdWQiOiIqIiwic3ViIjoiaHR0cDovL21zcGNzcHJzcnFhLmNvbmN1ci5jb25jdXJ0ZWNoLm9yZzozMDAzL3Byb2ZpbGUtc2VydmljZS92MS91c2Vycy83NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJpc3MiOiJodHRwczovL2NvbmN1ci5jb20iLCJleHAiOjE0NzM4OTUxMjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHA6Ly9tc3Bjc3Byc3JxYS5jb25jdXIuY29uY3VydGVjaC5vcmc6MzAwMy9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzYwMDlBRDMtRjc3Qi00RDk4LUEyMUEtNTUzQzlDOTE3OUYwIiwidXNlcnV1aWQiOiI3NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJuYmYiOjE0NzM4OTE1MjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vYXBwIjoiaHR0cHM6Ly9hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9hcHAtbWdtdC92MC9hcHBzL2UwMTBlMjVkLWI0Y2UtNGNlMy1hN2U0LWI2NzBjYjFhZGNiMCIsImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vc2NvcGVzIjpbIkNDQVJEIiwiQ09NUEQiLCJVU0VSIiwidXNlcl9yZWFkIiwiRU1FUkciLCJKT0JMT0ciLCJFUkVDUFQiLCJJVElORVIiLCJGSVNWQyIsIkxJU1QiLCJQQVNTViIsIkNPTkZJRyIsIkZPUCIsIkdIT1NUIiwiQ09OUkVRIiwiVFJJUElUIiwiQ09NUEFOWSIsInByb2ZpbGUiLCJFVlMiLCJlbWFpbCIsIlRSVlBUUyIsIkFUVEVORCIsIklOVlBPIiwiTk9USUYiLCJUUlZSRVEiLCJTVVBTVkMiLCJFWFBSUFQiLCJhZGRyZXNzIiwiRVhUUkNUIiwiUEFZQkFUIiwid3Jvbmdfc2NvcGUiLCJJTlZQTVQiLCJJTUFHRSIsIlRBWElOViIsIlJDVElNRyIsIlVOVVRYIiwiVFdTIiwiVE1DU1AiLCJCQU5LIiwiSU5WVkVOIiwib3BlbmlkIiwiTVRORyIsIklOU0dIVCIsIlRSVlBSRiIsIklOVlRWIiwiTUVESUMiLCJUU0FJIl0sImlhdCI6MTQ3Mzg5MTUyOX0.QHY4Mc5A3J981-HDv7KUdgS4tUI-qnmQAxwe9J6DHxuMmYSoGEYZ0dsnLnqc2lO2iVJK6Pg3EBZTArq8_vzV2FK7tA4-IT1eCEHo1e-RWZyWLnR7P56SvZozXpY73daovSH7572HrUm21FXcyLmdaLZyo2LfFcChaghbSCjm1Jg1duH-pLPUW4d89-_pdakmyxfV3GCm2N_XQXoRhNYAAiZcG8UfxEn3TpMHJ96F2n6keJanT_Sn2Sek_sH2EmeeCpg5-jDe0fvLvr1-gY5t0ifq8QBKWHSUUIrGbQvseD6CGzfyiFUqVypN2lukfWACR-26otN50c0OzY6kgY06RA

When you receive the accessToken, store it with the token's geolocation. That geolocation will be the base URI for all subsequent calls.

Armed with the accessToken you can start making calls to SAP Concur's API. Here's an example to retrieve profile information for a User in the Production environment using cURL (utilize the appropriate base URI geolocation for the token). Base URIs Reference:

curl -k -v -H "Accept: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJhdWQiOiIqIiwic3ViIjoiaHR0cDovL21zcGNzcHJzcnFhLmNvbmN1ci5jb25jdXJ0ZWNoLm9yZzozMDAzL3Byb2ZpbGUtc2VydmljZS92MS91c2Vycy83NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJpc3MiOiJodHRwczovL2NvbmN1ci5jb20iLCJleHAiOjE0NzM4OTUxMjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHA6Ly9tc3Bjc3Byc3JxYS5jb25jdXIuY29uY3VydGVjaC5vcmc6MzAwMy9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzYwMDlBRDMtRjc3Qi00RDk4LUEyMUEtNTUzQzlDOTE3OUYwIiwidXNlcnV1aWQiOiI3NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJuYmYiOjE0NzM4OTE1MjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vYXBwIjoiaHR0cHM6Ly9hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9hcHAtbWdtdC92MC9hcHBzL2UwMTBlMjVkLWI0Y2UtNGNlMy1hN2U0LWI2NzBjYjFhZGNiMCIsImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vc2NvcGVzIjpbIkNDQVJEIiwiQ09NUEQiLCJVU0VSIiwidXNlcl9yZWFkIiwiRU1FUkciLCJKT0JMT0ciLCJFUkVDUFQiLCJJVElORVIiLCJGSVNWQyIsIkxJU1QiLCJQQVNTViIsIkNPTkZJRyIsIkZPUCIsIkdIT1NUIiwiQ09OUkVRIiwiVFJJUElUIiwiQ09NUEFOWSIsInByb2ZpbGUiLCJFVlMiLCJlbWFpbCIsIlRSVlBUUyIsIkFUVEVORCIsIklOVlBPIiwiTk9USUYiLCJUUlZSRVEiLCJTVVBTVkMiLCJFWFBSUFQiLCJhZGRyZXNzIiwiRVhUUkNUIiwiUEFZQkFUIiwid3Jvbmdfc2NvcGUiLCJJTlZQTVQiLCJJTUFHRSIsIlRBWElOViIsIlJDVElNRyIsIlVOVVRYIiwiVFdTIiwiVE1DU1AiLCJCQU5LIiwiSU5WVkVOIiwib3BlbmlkIiwiTVRORyIsIklOU0dIVCIsIlRSVlBSRiIsIklOVlRWIiwiTUVESUMiLCJUU0FJIl0sImlhdCI6MTQ3Mzg5MTUyOX0.QHY4Mc5A3J981-HDv7KUdgS4tUI-qnmQAxwe9J6DHxuMmYSoGEYZ0dsnLnqc2lO2iVJK6Pg3EBZTArq8_vzV2FK7tA4-IT1eCEHo1e-RWZyWLnR7P56SvZozXpY73daovSH7572HrUm21FXcyLmdaLZyo2LfFcChaghbSCjm1Jg1duH-pLPUW4d89-_pdakmyxfV3GCm2N_XQXoRhNYAAiZcG8UfxEn3TpMHJ96F2n6keJanT_Sn2Sek_sH2EmeeCpg5-jDe0fvLvr1-gY5t0ifq8QBKWHSUUIrGbQvseD6CGzfyiFUqVypN2lukfWACR-26otN50c0OzY6kgY06RA" \
https://us.api.concursolutions.com/profile/v1/me

and the response will look like:

{
  "addresses": [
    {
      "type": "Home",
      "streetAddress": "",
      "locality": "",
      "region": "",
      "postalCode": "",
      "country": "US"
    },
    {
      "type": "Work",
      "streetAddress": "",
      "locality": "",
      "region": "",
      "postalCode": "",
      "country": "US"
    }
  ],
  "travelIds": {
    "userId": 85663431,
    "companyId": "63E447F6-A6A7-4B70-A951-10F45d693B43",
    "companyInternalId": 222458,
    "setId": 91157361,
    "ruleClassId": 394103,
    "travelConfigId": 0
  },
  "meta": {
    "created": "2016-06-08T00:00:00.000",
    "lastModified": "2016-08-22T14:32:00.000",
    "resourceType": "EnterpriseUser"
  },
  "displayName": "Brown",
  "name": {
    "formatted": "Brown, Terry ",
    "familyName": "Brown",
    "givenName": "Terry",
    "middleName": "",
    "honorificPrefix": "",
    "honorificSuffix": ""
  },
  "phoneNumbers": [
    {
      "type": "Home",
      "value": "tel:+1-4251231244",
      "primary": false,
      "notifications": false,
      "countryCode": "US",
      "countryISDCode": "1"
    },
    {
      "type": "Work",
      "value": "tel:+1-4251231234;ext=",
      "primary": false,
      "notifications": false,
      "countryCode": "US",
      "countryISDCode": "1"
    }
  ],
  "com:concur:Employee:1.0": {
    "employeeId": "brown@brown-sandbox.com",
    "jobTitle": "",
    "managerId": null,
    "orgUnitId": null
  },
  "dateOfBirth": null,
  "schemas": [
    "com:concur:User:1.0",
    "com:concur:Employee:1.0"
  ],
  "active": true,
  "id": "e01f725d-b4ce-4ce3-a664-b670cb5876cb0",
  "com:concur:TravelPreferences:1.0": {
    "air": {
      "seat": {
        "interrowPosition": null,
        "sectionPosition": null
      },
      "meal": "DontCare",
      "homeAirport": null
    },
    "rail": {
      "space": "DontCare",
      "meal": "DontCare",
      "bedCategory": "DontCare",
      "fareSpaceComfort": "DontCare",
      "deck": "DontCare",
      "coach": "DontCare",
      "bed": "DontCare",
      "berth": "DontCare",
      "noiseComfort": "DontCare",
      "contingency": "DontCare",
      "seat": "DontCare"
    },
    "car": {
      "smoking": "DontCare",
      "carType": "DontCare",
      "transmission": "DontCare",
      "gpsEnabled": false,
      "skirack": false
    },
    "hotel": {
      "earlyCheckin": false,
      "remark": null,
      "pool": false,
      "roomService": false,
      "foamPillows": false,
      "accessForBlind": false,
      "accessForWheelchair": false,
      "gym": false,
      "roomType": "DontCare",
      "restaurant": false,
      "rollawayBed": false,
      "smoking": "DontCare",
      "crib": false
    }
  },
  "gender": null,
  "emails": [
    {
      "value": "brown@brown-sandbox.com",
      "type": "Business",
      "notifications": true
    }
  ],
  "userType": "Enterprise"
}

Full docs: https://developer.concur.com/slate-ui/build/api-reference/user/

Access Token Expiry and Obtaining a Fresh One

Access Tokens have a default One hour lifetime. In order to obtain a fresh accessToken you need to call the auth endpoint using the Refresh Grant. This will return a brand new accessToken and a refreshToken. Refresh Tokens have a default 6 month lifetime. Clients will typically store the refreshToken together with the other user metadata like login information and unique identifiers.

Utilizing the geolocation for the token, here's an example of a cURL call to obtain a new accessToken

curl -X POST 'https://us.api.concursolutions.com/oauth2/v0/token' --data "client_id=$client_id&client_secret=$client_secret&grant_type=refresh_token&refresh_token=<old refresh token>"

Full docs: https://developer.concur.com/slate-ui/build/api-reference/authentication/apidoc.html#refresh_token

Now that you've made your first call, read up more about SAP Concur's wide ranging APIs and how they can enhance your application or solve your business needs.

ref: https://developer.concur.com/slate-ui/build/api-reference/index.html

Authentication

Special Note: (Please Read First)

If you are an existing partner with an existing app, please read both the Migration to Oauth2 Tokens and Getting Started documentation first. If you have any questions, please contact your Partner Enablement team representative before proceeding.

• Overview
• Tokens
  • Obtaining a token
  • Refreshing a token
  • Revoking a token
  • Token Management
  • Base URIs & Geolocation
  • ID Token
• Types of grants
  • Authorization grant
  • Password grant
  • Client Credentials grant
  • One Time Password grant
• Response Codes
• Troubleshooting

Note: The Pre-2017 Authorization (Deprecated) documentation be found here

Access Tokens

The Oauth2 service generates access tokens for authenticated users, applications or companies. The token returned in the Oauth2 response can be used to access protected resources on SAP Concur services.

The Oauth2 response can, depending on grant type contain these values:

Token Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

Obtaining a token

You can obtain a token for three different types of principals in the SAP Concur universe.

• User
• Application
• Company

Token Lifetime

An accessToken has a one hour lifetime.

In order to obtain a token, the client application needs to call the Oauth2 endpoint using various grants depending on the authentication scenarios required. The full list of supported scenarios is provided below:

• Authorization grant
• Password grant
• Client Credentials grant
• One Time Password grant

Refreshing a token

The refresh grant is used to refresh an access_token that has expired. This grant can be used anytime a refresh_token is returned in the response of another grant request. No user interaction is required.

Token Lifetime

A refresh token has a six month lifetime. If the refresh token expires, the client application must reinitiate the authorization process. When a refresh token is used to request a new access token, both a new access token as well as a new refresh token are returned in the response. This token can change even if most of the time, this value is the same. Client applications should treat all returned refresh tokens as new tokens and overwrite the stored tokens with the new token from the response.

It is recommended that the client application use the refresh grant to request a new access token as the initial step of accessing protected resources of SAP Concur services.

Refreshing the token

To request a new access token using a valid refresh token, use the Oauth2 /token endpoint. Use the application/x-www-form-urlencoded content type.

POST /oauth2/v0/token

Post Body

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=refresh_token
&refresh_token=valid-refresh_token
&scope=app-scope

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

Revoking a token

All refresh_tokens associated to a user for an application can be revoked by calling the https://us.api.concursolutions.com/app-mgmt/v0/connections endpoint with a DELETE action. You have to provide the User's accessToken in the Authorization Header as Authorization: Bearer <access_token>.

DELETE https://us.api.concursolutions.com/app-mgmt/v0/connections

Request

DELETE https://us.api.concursolutions.com/app-mgmt/v0/connections
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK

Managing tokens

Refresh Tokens are UUID4 identifiers that allow your application to obtain a fresh accessToken on behalf of a user to access SAP Concur APIs.

e013335d-b4ce-4c43-a7e4-b67abc1adcb0

It is highly recommended that you store Refresh Tokens together with your user's authorization metadata in your application every time you obtain a new refreshToken as they might change depending on different scenarios.

FOR APP CENTER AND SUPPLIER PARTNERS supporting all geolocations, storing the authorization metadata, including the geolocation are REQUIRED.

Base URIs

When making API calls, the appropriate base URI should be used. There are three different scenarios: 1. Obtaining a token for a user. 2. Refreshing a token. 3. Calling other APIs.

The base URI for obtaining a token will leverage your application's geolocation. The base URI for refreshing tokens and all other API calls will leverage the token's geolocation.

Base URIs for Obtaining a Token

When your application is created, you will be provided with a client ID, secret and geolocation. When obtaining a token, your application should use the base URI for the geolocation in which your application exists.

There are two endpoints for each geolocation - one is the default (used for server-side calls) and the other should be used for client-side calls.

The full list of available token geolocations is available on the Base URIs page.

When obtaining the token, the token's geolocation will be included in the response. The token's geolocation should be stored along with the token. The Developer's app will then be able to make subsequent calls using the token and the correct end points based on the token's GEO location.

Base URIs for All Other Calls

When refreshing a token or when calling any other APIs, the token's geolocation should be used as the base URI.

Note: Client-side calls should use the www- variant of the base URI.

For example: When obtaining a token, if the response was the below:

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

When then calling the receipts API to post a receipt, your request should be made to https://us.api.concursolutions.com (if server side) or https://www-us.api.concursolutions.com (for clients).

ID Token

Authentication service will return an OPENID compatible ID token with every token request. This id_token is primarily used to describe information about a user or a company. You can obtain the userId from this token.

Sample id_token:

{
  "aud": "e010e25d-b4ce-4ce3-a7e4-b670cb1adcb0",
  "concur.profile": "https://us.api.concursolutions.com/profile/v1/principals/76459ad3-f77b-4d98-a21a-55333c9179f0",
  "concur.version": 2,
  "concur.type": "user",
  "sub": "76459ad3-f77b-4d98-a21a-55333c9179f0",
  "iss": "https://us.api.concursolutions.com",
  "exp": 1485485529,
  "nbf": 1485481929,
  "at_hash": "351515a6482f4ee1",
  "iat": 1485481929
}

Verifying an id_token

The Authentication service exposes JWKs that can be used to validate the id_token in the form of a JWT. Validating a JWT is described in detail in RFC 7519 - sec 7.2

This is the link to the SAP Concur JSON Web Key for Oauth2. https://www-us.api.concursolutions.com/oauth2/v0/jwks

Authorization grant

The authorization grant is the regular 3-legged oauth2 grant and is defined in detail in RFC6749 sec-4.1. This grant requires the user to explicitly authenticate themselves and authorise the application initiating the grant.

The users must be able to authenticate themselves via an SAP Concur username & password. Users will be challenged to login by an Oauth2 HTML page.

Who should use it * 3rd party "partner" websites - or - * non-SAP Concur Applications - & - * Applications that need explicit user authentication & authorization - & - * Applications that can securely store a code, access_token & refresh_token

Grant details

Note that the grant type must be accessed using the www- version of the API Gateway in order to avoid certificate issues with some browsers. (ex: https://www-us.api.concursolutions.com instead of https://us.api.concursolutions.com)

GET /oauth2/v0/authorize

With this grant, the user has two authentication options: 1. Username and password 2. One-time link using a verified email address

With both options, once the user is successfully authenticated and the user authorizes your application, the user will be redirected to the redirect_URI specified in the initial /authorize call with a temporary token appended.

<redirect_uri>?geolocation=<token_geolocation>&code=<token>

If the user is not successfully authenticated or does not authorize the scopes for your application, an error code and description will be appended to the redirect URI. Please refer to the Response Codes section for more information.

Your application must then exchange the temporary token for a long-lived token using the below.

POST /oauth2/v0/token

Password grant

The Password grant can be used when there is a trust relationship between the user and the application. There are two credential types allowed with Password Grant:

1. "Password": with this credential type, the application either already has the user's credentials or can obtain the user's credentials by directly interacting with the user.
2. "AuthToken": This credential type is used for connections from the App Center. For App Center partners and TripLink suppliers, please refer to the certification documentation for more information.

Post Body

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 175

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=password
&username=username
&password=password

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

example bad login

{
  "error": "invalid_grant",
  "error_description": "Incorrect Credentials. Please Retry",
  "code": 5
}

Client Credentials grant

Use the application/x-www-form-urlencoded content type.

POST /oauth2/v0/token

Post Body

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 127

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=client_credentials

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 1626
Connection: Close

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "geolocation": "https://us.api.concursolutions.com"
}

One Time Password grant

The One-time Password grant type leverages email, phone (text messaging), instant messaging and similar systems to provide per user access tokens to client applications. This grant type requires the following steps:

1. The calling application calls the OAuth2 service specifying the otp grant type along with required parameters.
2. The OAuth2 service generates a one time token which it sends through the messaging mechanism chosen by the application.
3. The user retrieves the token and presents it to the application. The means of having this presented to the application is the responsibility of the application.
4. The application presents this one-time token to the OAuth2 service via the token endpoint.

Request a one-time token to be sent to the user

Use the application/x-www-form-urlencoded content type.

POST /oauth2/v0/otp

Post Body

The calling application code can also append n-number of unique client defined parameters in the URI for the purpose of connecting the one time token to the application when received by the user. The names of these parameters cannot conflict with the API defined parameters.

The following are reserved words and cannot be used as client application defined parameters:

/otp: "client_id" "client_secret" "channel_type" "channel_handle"

/token: "client_id" "client_secret" "channel_type" "channel_handle" "scope" "grant_type" "otp"

If the calling application chooses to send custom parameters, all of these exact same parameters must be included in subsequent API calls to acquire the access token. In other words, the URI signature, modulo the one time token parameter itself and token service specific parameters, must match the originating URI signature.

Request

POST /oauth2/v0/otp HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&channel_handle=email adress
&channel_type=valid-email
&link=https://example.com/callback

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 22
Date: date-requested

{
  "message": "otp sent"
}

Request an access token

The One Time Password grant requires that all of the parameters, including client application defined parameters to be sent in the request body when requesting an access token. Use the application/x-www-form-urlencoded content type.

POST oauth2/v0/token

Post Body

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&channel_handle=email adress
&channel_type=valid-email
&scope=app_scope
&grant_type=otp
&otp=one-time-token

Response

HTTP/1.1 200 OK
Date: date-requested
Content-Length: 1490
Connection: keep-alive

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

Response Codes

HTTP Status returned by oauth2

4xx class errors have a JSON response with the following fields

{
  "code": <number>,
  "error": <error>,
  "error_description": <error_description>,
  "geolocation": <geolocation url where user lives>
}

/authorize

If the authorization or authentication are unsuccessful, your application will receive an error code and description at the redirect_uri provided.

 error_code=<>
 &error_description=<>

In all cases, the friendly error description should be displayed to the user.

/token

/otp

Troubleshooting

In order to assist with troubleshooting, SAP Concur responds with a unique correlationId in the response header. The key to look for is correlationid. This unique code can be used during troubleshooting as it identifies the API call in the log files. You should record this information in your own API call logs as well so that you can pass this information on to the SAP Concur support team.

Example of the correlationid in the response:

< HTTP/1.1 200 OK
< Server: cnqr-papeete
< Date: Mon, 04 Dec 2017 22:07:05 GMT
< Content-Type: application/json
< Content-Length: 2897
< Connection: keep-alive
< Concur-Correlationid: 2803b8f8-a42b-43c2-a739-b8768e4759b8

Enterprise Business Applications

Only the Password Grant Type is available for obtaining company-level tokens.

1. To begin the authentication flow, a Customer's SAP Concur Administrator clicks on the Connect button within the App Center listing and authorizes the partner's app. This app listing is located within customer's SAP Concur system's App Center tab.
2. The SAP Concur authorization service will redirect the Admin to the Partner’s Landing Page. Partners should follow the App Center UX Guidelines to create a web page that listens for an HTTP GET request from SAP Concur.
3. The redirect URI will contain an id, requestToken and userId parameters. Example: https://{partner_redirect_URI}?id=8568a4cd-8ffc-49d6-9417-be2d69aa075f&requestToken=5l85ae5a-426f-4d6f-8af4-08648c4b696b&userId=9bdded51-00b8-4f84-8bef-6d3afe727007
4. When the Partner application receives the redirect call, the Partner should strip the id and requestToken values from the URI and use those on a Post request to the SAP Concur Authorization service to obtain the official Oauth2 Access Token and Refresh Token for the customer using the password grant. As explained in detail in this presentation, the Partner must have Data Center Geo Awareness related to the token. We currently have 3 Data Centers and the API end points change based on these Data Centers so it is imperative the proper token management is followed. Otherwise, your app will not make the correct call per Access token.
5. An access token is valid for only one hour. The access token should be cached in memory and discarded after use.
6. After the Admin has successfully completed the login/enrollment process, the Partner should store the following elements with the customer’s profile metadata.
   • refresh_token: (36 characters including dashes) Valid for six months from the day and time issued.
   • refresh_expires_in: This is Epoch time format, convert to UTC.
   • geolocation: To be used when making API calls on behalf of the customer.
   • id: Aka sub, is the customer’s unique identifier (UUID). It can be retrieved from the following sources:
   • From the re-direct URI as the id element.
   • By decoding the id_token returned with Access token, as the sub element. (See https://jwt.io)
7. It is highly recommended that Partners log the following elements:
   • userId: the user who clicked on the Connect button (returned in the re-direct URI)
   • correlationid: SAP Concur responds with a unique code which identifies the API call in the log files. (returned in the response header). More details can be found here.

Company Level Authentication

• Overview
• Company
• Obtaining a one-time auth token
• Response Codes

Company

Company is a top-level principal within Concur and you would be able to obtain an access token and a refresh token on a Company's behalf just like you would be able to with a User. Only one authorization flow is currently available for obtaining tokens for a Company, which is the Password grant using a temporary auth token received from the App Center.

Obtaining A One-Time Auth Token

To begin the authentication flow for a company, one must first obtain a temporary auth token through AppCenter's interface. AppCenter will request for a temporary auth token and hand it off to the partner, who will then in turn use Password grant to exchange the temporary auth token for a full access token and refresh token for the company.

Auth tokens are valid only for 12 hours. Partners have 12 hours to exchange the auth token for a refresh and access token, and can use this auth token multiple times within the 12 hours in case of network failure.

This auth flow diagram describes this handshake:

Company Authentication Flow Sequence Diagram

AppCenter will call this endpoint to obtain an authToken. (on right)

AppCenter will call this endpoint to obtain an authToken:

(HTTP)

POST /profile-service/v1/keys/principals/<companyId>/authtoken/

Sample Curl: (on right) ```shell

(CURL)

curl -E appcenter.p12:. -H 'concur-correlationid: githbuwiki' -XPOST https://us.api.concursolutions.com/profile-service/v1/keys/principals/08BCCA1E-0D4F-4261-9F1B-F778D96617D6/authtoken/

```shell
200 OK

{
  "status": "PASS",
  "code": 0,
  "errormsg": "",
  "token": "<authToken>"
}

AppCenter redirects User to Client's auth handler URI (Connect URL) and passing in the authToken

301 Redirect https://client.app.url?id=$company_uuid&requestToken=$request_token&userID=$user_uuid

At this point, the user should be prompted to sign in to your application. If the user doesn't not have account, the user should have the ability to create one. For applications that have user read scope, the User UUID can be used to pre-populate the account creation forms. Please see the App Center User Experience guidelines for more information.

Client app calls Oauth2 password grant to get an access token for the company

See Example Request and Response

Example Request and Response

(Request)

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 175

client_id=your-client_id
&client_secret=your-client_secret
&grant_type=password
&username=<companyId>
&password=<authtoken>
&credtype=authtoken

(RESPONSE: Success)

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close 

{
  "expires_in": "3600",
  "scope": "app_scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "geolocation":"https://us.api.concursolutions.com"
}

(RESPONSE: Failure)

{
  "error": "invalid_grant",
  "error_description": "Incorrect Credentials. Please Retry",
  "code": 5
}

Company Level Authentication - Response Codes

HTTP Status Code returned by oauth2

4xx class errors have a JSON response with the following fields

{
  "code": "<number>",
  "error": "<error>",
  "error_description": "<error_description>"
}

/token

Migrating old tokens to new Oauth2 Bearer Tokens

• Base URIs
• Exchanging a Token
• Response Codes

Existing applications that use the Pre-2017 Authorization (Deprecated) framework need to move to support the new Oauth2 Bearer Tokens. Applications will need to migrate their existing users who already have connected to it to obtain new Oauth2 tokens without requiring users to reauthorize. This can be done by exchanging an old access token for a new refresh token.

Base URIs

When making API calls, the appropriate base URI for the user's geolocation should be used. See the Base URIs page for the full list.

Exchanging a Token

In order to support new Oauth2, applications need to exchange old access token for new accessToken and refreshToken pair. Once obtained, applications should store these refreshTokens as part of users authorization data.

The new Oauth2 accessToken has a one hour lifetime. Once expired, applications would need to call Oauth2's /v0/token endpoint using a refresh_grant, passing in the user's refreshtoken to obtain a fresh accessToken.

This is significantly different from how the deprecated /net2/Oauth2's method of handling access tokens. Partner's would have to store the new Oauth2 refreshToken instead of the old access token. Before making a call to any of Concur's new v4 APIs, it is advisable to request for a new accessToken before making the API call.

Step 1: Obtain Application Token Clients can exchange OLD tokens for NEW Oauth2 tokens by calling the exchangeRefreshToken/me endpoint. In order to call this endpoint, you would first need to obtain an Application Token by calling the /v0/token endpoint with the client_credentials grant.

The endpoint also supports a parameter called "returnType=companyToken" This parameter allows a partner who already has what is known as a "WSAdmin" token for a client, to exchange that token for a Company level refresh token.

Step 2: Call exchangeRefreshToken

POST /appmgmt/v0/legacyApps/{OLDConsumerKey}/exchangeRefreshToken/me

If you are exchanging a WSAdmin token for a new Company level refresh token:

POST /appmgmt/v0/legacyApps/{OLDConsumerKey}/exchangeRefreshToken/me?returnType=companyToken

Request Header

Request Body

Sample Curl:

curl -H 'Authorization: Bearer <accessToken>' -d '{"token": "1_oaCof444CaiNXg1FFG$Perr19qIo", "secret": "12345"}' -X POST https://us.api.concursolutions.com/appmgmt/v0/legacyApps/Bwu0mvTHtKYAnBb3Pgu9AW/exchangeRefreshToken/me

successful call, responds with

200 OK
{
  "token": "8c844478-745c-4c45-adf7-1e2777a50dbf",
  "created": 1479407196809,
  "expired": 1494959196809,
  "scopes": [
    "EXPRPT",
    "LIST",
    "BANK",
    "CCARD"
  ],
  "context": "{\"userid\":\"7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"cid\":\"3a55c75e-ac1e-4515-845c-0a4978452828\",\"ptype\":\"user\",\"userURI\":\"https://us.api.concursolutions.com/profile-service/v1/users/7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"scope\":\"EXPRPT LIST BANK CCARD\"}"
}

Sample Curl for WSAdmin token exchange for Company level refreh token:

curl -H 'Authorization: Bearer <accessToken>' -d '{"token": "1_oaCof444CaiNXg1FFG$Perr19qIo", "secret": "12345"}' -X POST https://us.api.concursolutions.com/appmgmt/v0/legacyApps/Bwu0mvTHtKYAnBb3Pgu9AW/exchangeRefreshToken/me?returnType=companyToken

successful call, responds with

200 OK
{
  "token": "8c844478-745c-4c45-adf7-1e2777a50dbf",
  "created": 1479407196809,
  "expired": 1494959196809,
  "scopes": [
    "EXPRPT",
    "LIST",
    "BANK",
    "CCARD"
  ],
  "context": "{\"userid\":\"7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"cid\":\"3a55c75e-ac1e-4515-845c-0a4978452828\",\"ptype\":\"company\",\"userURI\":\"https://us.api.concursolutions.com/profile-service/v1/users/7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"scope\":\"EXPRPT LIST BANK CCARD\"}"
}

Step 3: Obtain New Access Token

Once you have the NEW refreshToken from the response (8c844478-745c-4c45-adf7-1e2777a50dbf) you can then proceed to call /v0/token using the refresh grant to obtain a NEW Oauth2 accessToken.

Sample Curl:

curl -X POST 'https://us.api.concursolutions.com/oauth2/v0/token' -d 'client_id=3a55c75e-ac1e-4515-845c-0a4978452828&client_secret=12345&grant_type=refresh_token&refresh_token=8c844478-745c-4c45-adf7-1e2777a50dbf'

successful call, responds with:

200 OK
{
  "expires_in": 3600,
  "scope": "EXPRPT LIST BANK CCARD",
  "token_type": "Bearer",
  "access_token": "eyJ0...demo...eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJjb25jdXIuc2NvcGVzIjpbIkVYUFJQVCIsIkxJU1QiLCJCQU5LIiwiQ0NBUkQiXSwiYXVkIjoiKiIsImNvbmN1ci5wcm9maWxlIjoiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvcHJpY2lwYWxzLzc5NmI0NjdmLWRjZDEtNDYzMS1iYTg1LTNlYmQyOGIzNmU4ZiIsImNvbmN1ci52ZXJzaW9uIjoyLCJjb25jdXIudHlwZSI6InVzZXIiLCJjb25jdXIuYXBwIjoiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvYXBwcy9lMDEwZTI1ZC1iNGNlLTRjZTMtYTdlNiLCJzdWIiOiI3OTZiNDY3Zi1kY2QxLTQ2MzEtYmE4NS0zZWJkMjhiMzZlOGYiLCJpc3MiOiJodHRwczovL3VzLXJxYTMuYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20iLCJleHAiOjE0Nzk0MTU4NjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHBzOi8vdXMtcnFhMy5hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzk2YjQ2N2YtZGNkMS00NjMxLWJhODUtM2ViZDI4YjM2ZThmIiwidXNlcnV1aWQiOiI3OTZiNDY3Zi1kY2QxLTQ2MzEtYmE4NS0zZWJkMjhiMzZlOGYiLCJuYmYiOjE0Nzk0MTIyNjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucyiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvYXBwcy9lMDEwZTI1ZC1iNGNlLTRjZTMtYTdlNC1iNjcwY2IxYWRjYjAiLCJodHRwczovL2FwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Njb3BlcyI6WyJFWFBSUFQiLCJMSVNUIiwiQkFOSyIsIkNDQVJEIl0sImlhdCI6MTQ3OTQxMjI2OX0.I4EeqKZbpfFonitGBZnLBb20NwMjZNNp5e1d3-BRsepEcJSVCVYIV9HAB2EkkopvoLJsAittiZgD0iDwuh2WVgUt_c4QGzNc_-rXRtCIeKyPQRvxUZNQ7y5RTqEQFNo7hrtXiNZ-yV30zlbijP-12XU5Cu4n2VXgRKxvcCUr5j0RcovUc6O0aOR7VTzj4ZbiDdijOEtmKWGluAYyfIlz8XF2aErAB5Jff2fr9UvgHgtbleYV7eBSesvd9hJEk4S-OAtmFoJwLDECLtLcBKyeHnPEe7LmkLYShcflWG2_tYk4ysPIMG6ne5kRNxJKsDbkMItjpXhujBEGi7YIPWtFWQ",
  "refresh_token": "31456dcd-b46a-4292-b2d3-f97033338487",
  "geolocation": "https://us.api.concursolutions.com"
}

Migration - Response Codes

HTTP Status returned by exchangeAccessToken

exchangeAccessToken Response Codes

HTTP Status returned by oauth2

4xx class errors have a JSON response with the following fields

{
  "code": <number>,
  "error": <error>,
  "error_description": <error_description>
}

/token

Oauth2 Migration Best Practices

• Old World Authentication
• New World Authentication
  • Oauth2
  • Getting Started
  • Token Management
  • Old Auth v.s. New Auth Diagram

Old World Authentication

• The old world authentication is a hybrid oauth2 implementation which has an endpoint that looks like this /net2/oauth2/
• Client applications are identified by a ConsumerKey and Secret pair. Sometimes these are referred to as client_id and client_secret.
• Access Tokens in the old world have a 12 months expiry period and refresh tokens live forever. This is typically not a good security practice and goes against the Oauth2 standards.
• Tokens that are being used by clients today are issued for WSADMINs, meaning all tokens have administrative access.

New World Authentication

1. Oauth2

• SAP Concur's new Oauth2 implementation follows the established Oauth2 Authorization Framework RFC : https://tools.ietf.org/html/rfc6749
• This new service has an endpoint of /oauth2/v0/token
• Unlike the old world auth, access tokens have a 1 hour expiry and refresh tokens have a 6 months expiry. This is in accordance to the best practice of using short lived tokens.
• This would mean that clients would need to perform token management.

2. Oauth2 Migration - Getting Started

• Getting clientID / clientSecret
  • Work with SAP Concur's implementation team to obtain a new oauth2 client_id and client_secret and to define the scope of client's application.
  • Process will take no longer than 48 hours.
  • Implementation Team will respond with new client_id, client_secret, company's refreshToken and expiry date.
  • Client stores and configures application with this info.
• Client applications should store the following tokens and data in their application.
  • Refresh Token: This token can change although most of the time this value is the same. Client applications should treat all returned refresh tokens as new values and overwrite the stored values with the new values you get from the response.
  • Refresh Token Expiry: This date should be checked by a daily script and ensure that a refresh_grant is made to keep the refresh token alive indefinitely. If company policy dictates that the token should be allowed to expire, then you can skip this step. Once a refresh token has expired, clients would need to contact SAP Concur's Implementation team to get a new company token.

3. Token Management

• Calling APIs with accessTokens

  • All APIs within SAP Concur require the calling application present an accessToken in the Header using the "Bearer" keyword.
  • Example: curl -k -v -H "Accept: application/json" \ -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJhdWQiOiIqIiwic3ViIjoiaHR0cDovL21zcGNzcHJzcnFhLmNvbmN1ci5jb25jdXJ0ZWNoLm9yZzozMDAzL3Byb2ZpbGUtc2VydmljZS92MS91c2Vycy83NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJpc3MiOiJodHRwczovL2NvbmN1ci5jb20iLCJleHAiOjE0NzM4OTUxMjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHA6Ly9tc3Bjc3Byc3JxYS5jb25jdXIuY29uY3VydGVjaC5vcmc6MzAwMy9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzYwMDlBRDMtRjc3Qi00RDk4LUEyMUEtNTUzQzlDOTE3OUYwIiwidXNlcnV1aWQiOiI3NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJuYmYiOjE0NzM4OTE1MjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vYXBwIjoiaHR0cHM6Ly9hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9hcHAtbWdtdC92MC9hcHBzL2UwMTBlMjVkLWI0Y2UtNGNlMy1hN2U0LWI2NzBjYjFhZGNiMCIsImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vc2NvcGVzIjpbIkNDQVJEIiwiQ09NUEQiLCJVU0VSIiwidXNlcl9yZWFkIiwiRU1FUkciLCJKT0JMT0ciLCJFUkVDUFQiLCJJVElORVIiLCJGSVNWQyIsIkxJU1QiLCJQQVNTViIsIkNPTkZJRyIsIkZPUCIsIkdIT1NUIiwiQ09OUkVRIiwiVFJJUElUIiwiQ09NUEFOWSIsInByb2ZpbGUiLCJFVlMiLCJlbWFpbCIsIlRSVlBUUyIsIkFUVEVORCIsIklOVlBPIiwiTk9USUYiLCJUUlZSRVEiLCJTVVBTVkMiLCJFWFBSUFQiLCJhZGRyZXNzIiwiRVhUUkNUIiwiUEFZQkFUIiwid3Jvbmdfc2NvcGUiLCJJTlZQTVQiLCJJTUFHRSIsIlRBWElOViIsIlJDVElNRyIsIlVOVVRYIiwiVFdTIiwiVE1DU1AiLCJCQU5LIiwiSU5WVkVOIiwib3BlbmlkIiwiTVRORyIsIklOU0dIVCIsIlRSVlBSRiIsIklOVlRWIiwiTUVESUMiLCJUU0FJIl0sImlhdCI6MTQ3Mzg5MTUyOX0.QHY4Mc5A3J981-HDv7KUdgS4tUI-qnmQAxwe9J6DHxuMmYSoGEYZ0dsnLnqc2lO2iVJK6Pg3EBZTArq8_vzV2FK7tA4-IT1eCEHo1e-RWZyWLnR7P56SvZozXpY73daovSH7572HrUm21FXcyLmdaLZyo2LfFcChaghbSCjm1Jg1duH-pLPUW4d89-_pdakmyxfV3GCm2N_XQXoRhNYAAiZcG8UfxEn3TpMHJ96F2n6keJanT_Sn2Sek_sH2EmeeCpg5-jDe0fvLvr1-gY5t0ifq8QBKWHSUUIrGbQvseD6CGzfyiFUqVypN2lukfWACR-26otN50c0OzY6kgY06RA" \ https://us.api.concursolutions.com/profile/v1/me
  • More documentation here: https://developer.concur.com/slate-ui/build/api-reference.html#getting-started.html

• Refreshing expired accessTokens

  • Since accessTokens have a one hour expiry, clients would need to get a new accessToken before any API call is made.
  • In order to obtain a new accessToken, clients should call Oauth2 using the refresh_grant and providing the old refreshToken and other additional fields.

  • In the error handling code, clients need to handle accessToken expiry errors. If the accessToken is expired in the middle of processing, the following should happen:

    • Code should call Oauth2's refresh_grant to get a new accessToken
    • Overwrite the existing refreshToken with the new one.
    • Update expiry date for refreshToken
    • Retry the API call.

  • More details about refreshing tokens here: https://developer.concur.com/slate-ui/build/api-reference.html#refresh_token

• Handling errors

  • There are a few error codes that client applications should be aware of.
  • 403 Forbidden: Requesting for tokens for users who cannot be requested for. Usually for companies that are not authorized by their administrators.
  • The bulk of errors will be returned as 400 errors and the response contains a code and description. Client applications should look for these values to determine what to do next.

  Code	Desc	Comment
  05	Incorrect credentials.	clientID / secret not correct, or authtoken/password not correct
  10	Account is disabled
  14	Account is locked
  16	User lives elsewhere	There will be a geolocation field in the response to this error message. Use this as the base URL and retry the call.
  54	Invalid Scope	requested scope exceeds what is permitted.

  • for a full list, review this doc: https://developer.concur.com/slate-ui/build/api-reference.html#response_codes

4. Old auth v.s. new auth diagram

List of Scopes for all SAP Concur APIs

• Naming Conventions
• List of v4 Actions
• List of v4 API Scopes
• List of Connect API scopes

Scope is a parameter as defined in the OAuth 2.0 standards (RFC6749) to enable a client to specify the scope of the access request. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings although some implementations of scope uses a comma-delimited format. Scopes limit access for OAuth2 tokens and do not grant any additional permission beyond that which the client already has.

Scopes apply to applications only. Scopes play a crucial part in defining the ultimate access to a resource by a User.

User’s Roles / Permissions + Claims + Application Scopes

Naming Conventions

Concur services follow these standard naming conventions for scopes.

Template: {resource}.{optional subresource}.{action}
Examples: mileage.rate.read
          receipts.read

List of v4 Actions

{actions} are common authorizations across resources.

List of v4 API Scopes

These are the list of scopes for the v4+ APIs.

List of Connect API scopes

These are the list of scopes for the existing CONNECT APIs (v1.0 - v3.1)

Budget v4

Budget v4 - Getting Started

Menu

• Getting Started
• Fiscal Year
• Budget Category
• Budget Item
• Budget Tracking Field
• Budget Adjustments

Getting Started

• Overview
• Process Flow
• Products and Editions
• Scope Usage
• Dependencies
• Access Token Usage

Overview

The Budget service exposes budget and fiscal year data. Partners and clients may use the service endpoints to read and alter fiscal year, budget, budget adjustment, and budget matching configuration. Summary and detailed balance amounts are also available to read, but may not be altered via the API.

The sequence to configure budgets is to first setup the fiscal year and then the budget categories (if applicable) before creating budget items. Budget items may use budget tracking fields as filters. The budget tracking field can only be configured in the application UI. Also budget owner, approver, and budget viewer permissions have to be assigned to users prior to configuring budgets.

Process Flow

Products and Editions

• Concur Request Professional Edition
• Concur Request Standard Edition
• Concur Expense Professional Edition
• Concur Expense Standard Edition
• Concur Invoice Professional Edition
• Concur Invoice Standard Edition

Scope Usage

This API requires one or more of the following scopes:

Dependencies

SAP Concur clients must purchase Budget in order to use this API.

Access Token Usage

This API supports both company level and user level access tokens. The user needs to have the Budget Administrator role in order to access the API.

Budget v4 - Fiscal Year 2020

Menu

• Getting Started
• Fiscal Year
• Budget Category
• Budget Item
• Budget Tracking Field
• Budget Adjustments
• Budget API Explorer

The Fiscal Calendar is used both for Reporting and Budget. A fiscal year can start and end at any date as long as the end date is after the start date and does not span more than two years. Fiscal years cannot overlap. Fiscal periods cannot overlap and are limited to 24 per fiscal year.

• GET All Fiscal Years
• GET a Fiscal Year
• POST a Fiscal Year
• DELETE a Fiscal Year
• Schema
  • Fiscal Year
  • Fiscal Period
  • Error Response
  • Error Message

GET All Fiscal Years

Retrieve a list of all fiscal years

• Use the lastModifiedAfter parameter if you wish to only retrieve fiscal years that were changed after a certain date.
• Use the includeRemoved parameter if you wish to retrieve all fiscal years, including those that have been deleted. Important: deleted data that is beyond the configured retention period can not be returned.

Scopes

This API call requires one of the following scopes:

• budgetitem.read - Refer to Scope Usage for full details.
• budgetitem.write - Refer to Scope Usage for full details.
• fiscalyear.read - Refer to Scope Usage for full details.
• fiscalyear.write - Refer to Scope Usage for full details.

Request

URI

GET  /budget/v4/fiscalYear

Template

Parameters

Headers

• RFC 7235 Authorization
• RFC 7231 Content-Type

Response

Status Codes

• 200 OK Successful call, response is in body.
• 400 Bad Request The request was determined to be invalid by the server.
• 403 Forbidden The user does not have the necessary permissions to perform the request.
• 500 Internal Server Error Error message in response body.
• 504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Fiscal Year

Example

GET https://us.api.concursolutions.com/budget/v4/fiscalYear?lastModifiedAfter=2017-02-27T12:30:00
Authorization: Bearer {token}
Content-Type: application/json

Request

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 2187
concur-correlationid: ffa4ae0a-f65c-4037-8bfb-8996c3fca28c

Response

[
    {
      "name":"2017",
      "startDate":"2017-01-01",
      "endDate":"2017-12-31",
      "status":"OPEN",
      "id":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "lastModified":"2017-03-26 20:53:19",
      "currentYear":false,
      "monthlyFiscalPeriods":[
        {
          "name":"2017 - Aug",
          "fiscalPeriodStatus":"OPEN",
          "id":"a4e94128-c7b7-4561-a57e-1512e59e4896",
          "periodType":"MONTHLY",
          "startDate":"2017-08-01",
          "endDate":"2017-08-31",
          "spendDate":null,
          "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
          "currentPeriod":false
        },
        {
          "name":"2017 - Jan",
          "fiscalPeriodStatus":"CLOSED",
          "id":"ab2810f5-f045-45b0-b2b2-8e84bc978e27",
          "periodType":"MONTHLY",
          "startDate":"2017-01-01",
          "endDate":"2017-01-30",
          "spendDate":null,
          "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
          "currentPeriod":false
        },
        {
          "Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
        }
      ],
      "quarterlyFiscalPeriods":[
        {"name":"2017 - Q4",
          "fiscalPeriodStatus":"OPEN",
          "id":"655ffe9d-caca-4f2f-a4a1-e04cfb68fd6e",
          "periodType":"QUARTERLY",
          "startDate":"2017-10-01",
          "endDate":"2017-12-31",
          "spendDate":null,
          "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
          "currentPeriod":false
        },
        {
          "Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
        }
      ],
      "yearlyFiscalPeriods":[
        {
          "name":"2017",
          "fiscalPeriodStatus":"OPEN",
          "id":"2fb8ea93-172a-47a6-9611-44eb75ad547b",
          "periodType":"YEARLY",
          "startDate":"2017-01-01",
          "endDate":"2017-12-31",
          "spendDate":null,
          "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
          "currentPeriod":false
        }
      ],
      "customFiscalPeriods":[]
    }
]

GET a Fiscal Year

Retrieve a single fiscal year by ID.

Scopes

This API call requires one of the following scopes:

• budgetitem.read - Refer to Scope Usage for full details.
• budgetitem.write - Refer to Scope Usage for full details.
• fiscalyear.read - Refer to Scope Usage for full details.
• fiscalyear.write - Refer to Scope Usage for full details.

Request

URI

Template

GET  /budget/v4/fiscalYear/{id}

Parameters

Headers

• RFC 7235 Authorization
• RFC 7231 Content-Type

Response

Status Codes

• 200 OK Successful call, response is in body.
• 400 Bad Request The request was determined to be invalid by the server.
• 403 Forbidden The user does not have the necessary permissions to perform the request.
• 404 Not Found The resource could not be found or does not exist.
• 500 Internal Server Error Error message in response body.
• 504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Fiscal Year

Example

GET https://us.api.concursolutions.com/budget/v4/fiscalYear/5e58b9b1-fed6-4d36-a5a1-a1ed325931d4
Authorization: Bearer {token}

Request

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 39216840-2808-4c49-8874-e9862d96fdb6

Response

{
  "name":"2017",
  "startDate":"2017-01-01",
  "endDate":"2017-12-31",
  "status":"OPEN",
  "id":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
  "lastModified":"2017-03-26 20:53:19",
  "currentYear":false,
  "monthlyFiscalPeriods":[
    {
      "name":"2017 - Aug",
      "fiscalPeriodStatus":"OPEN",
      "id":"a4e94128-c7b7-4561-a57e-1512e59e4896",
      "periodType":"MONTHLY",
      "startDate":"2017-08-01",
      "endDate":"2017-08-31",
      "spendDate":null,
      "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "currentPeriod":false
    },
    {
      "name":"2017 - Jan",
      "fiscalPeriodStatus":"CLOSED",
      "id":"ab2810f5-f045-45b0-b2b2-8e84bc978e27",
      "periodType":"MONTHLY",
      "startDate":"2017-01-01",
      "endDate":"2017-01-30",
      "spendDate":null,
      "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "currentPeriod":false
    },
    {
      "Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
    }
  ],
  "quarterlyFiscalPeriods":[
    {"name":"2017 - Q4",
      "fiscalPeriodStatus":"OPEN",
      "id":"655ffe9d-caca-4f2f-a4a1-e04cfb68fd6e",
      "periodType":"QUARTERLY",
      "startDate":"2017-10-01",
      "endDate":"2017-12-31",
      "spendDate":null,
      "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "currentPeriod":false
    },
    {
      "Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
    }
  ],
  "yearlyFiscalPeriods":[
    {
      "name":"2017",
      "fiscalPeriodStatus":"OPEN",
      "id":"2fb8ea93-172a-47a6-9611-44eb75ad547b",
      "periodType":"YEARLY",
      "startDate":"2017-01-01",
      "endDate":"2017-12-31",
      "spendDate":null,
      "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "currentPeriod":false
    }
  ],
  "customFiscalPeriods":[],
  "displayName":"2017-Special"
}

POST Fiscal Year(s)

Create or update a list of one or more fiscal years.

• Fiscal years may be created for the future or the past
• Unless there is a need to do so, the client should only specify monthly fiscal periods when creating/updating a fiscal year. The system will auto-generate the quarterly and yearly fiscal periods.

Scopes

This API call requires one of the following scopes:

• budgetitem.write - Refer to Scope Usage for full details.
• fiscalyear.write - Refer to Scope Usage for full details.

Request

URI

Template

POST  /budget/v4/budgetCategory

Parameters

N/A

Headers

• RFC 7235 Authorization
• RFC 7231 Content-Type

Payload

Fiscal Year

Response

Status Codes

• 200 OK Successful call, response is in body.
• 400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
• 403 Forbidden The user does not have the necessary permissions to perform the request.
• 404 Not Found The resource could not be found or does not exist.
• 500 Internal Server Error Error message in response body.
• 504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Fiscal Year or Error Response

Example

POST https://us.api.concursolutions.com/budget/v4/fiscalYear
Authorization: Bearer {token}

Request

[
  {
    "name":"2017-Special",
    "startDate":"2017-01-01",
    "endDate":"2017-03-31",
    "status":"OPEN",
    "monthlyFiscalPeriods":[
      {
        "name":"2017-Special - Jan",
        "fiscalPeriodStatus":"OPEN",
        "periodType":"MONTHLY",
        "startDate":"2017-01-01",
        "endDate":"2017-01-31"
      },
      {
        "name":"2017-Special - Feb",
        "fiscalPeriodStatus":"OPEN",
        "periodType":"MONTHLY",
        "startDate":"2017-02-01",
        "endDate":"2017-02-28"
      },
      {
        "name":"2017-Special - Mar",
        "fiscalPeriodStatus":"OPEN",
        "periodType":"MONTHLY",
        "startDate":"2017-03-01",
        "endDate":"2017-03-31"
      }
    ],
    "displayName":"2017-Special"
  }
]

Response

Success Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 5c00e59f-d00c-4019-8d3d-47130d8e37b4

[
    {
      "name":"2017-Special",
      "startDate":"2017-01-01",
      "endDate":"2017-03-31",
      "status":"OPEN",
      "id":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
      "lastModified":"2018-03-26 20:54:11",
      "currentYear":false,
      "monthlyFiscalPeriods":[
        {
          "name":"2017-Special - Jan",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-01-01",
          "endDate":"2017-01-31",
          "id":"1929d1d9-6c99-4635-9272-508364193f8f",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        },
        {
          "name":"2017-Special - Feb",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-02-01",
          "endDate":"2017-02-28",
          "id":"41aa7452-e52a-4fd6-9c8a-5b199edeadaf",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        },
        {
          "name":"2017-Special - Mar",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-03-01",
          "endDate":"2017-03-31",
          "id":"6c7d0b13-96b9-4d76-a083-4d38c96144e2",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        }
      ],
      "quarterlyFiscalPeriods":[
        {
          "name":"2017-Special - Q1",
          "fiscalPeriodStatus":"OPEN",
          "id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
          "periodType":"QUARTERLY",
          "startDate":"2017-01-01",
          "endDate":"2017-03-31",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        }
      ],
      "yearlyFiscalPeriods":[
        {
          "name":"2017-Special",
          "fiscalPeriodStatus":"OPEN",
          "id":"a6bede66-4f3d-412f-a620-2a073013cb2a",
          "periodType":"YEARLY",
          "startDate":"2017-01-01",
          "endDate":"2017-03-31",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        }
      ],
      "customFiscalPeriods":[],
      "displayName":"2017-Special"
    }
]

Failure Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 338
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: cb061832-82eb-418e-a968-de6b4ce370ae

{
  "status" : false,
  "errorMessageList" : [
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.FISCAL_YEAR_SDATE_ERROR",
      "errorMessage" : "Fiscal year should have a start date"
    },
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.FISCAL_YEARS_HAVE_GAP",
      "errorMessage" : "Fiscal years should not have gaps between them"
    }
  ]
}

DELETE a Fiscal Year

Delete a fiscal year. Fiscal years that are in use may not be deleted.

Scopes

This API call requires one of the following scopes:

• budgetitem.write - Refer to Scope Usage for full details.
• fiscalyear.write - Refer to Scope Usage for full details.

Request

URI

Template

DELETE  /budget/v4/fiscalYear/{id}

Parameters

Headers

• RFC 7235 Authorization
• RFC 7231 Content-Type

Response

Status Codes

• 200 OK Successful call, response is in body.
• 400 Bad Request The request was determined to be invalid by the server.
• 403 Forbidden The user does not have the necessary permissions to perform the request.
• 404 Not Found The resource could not be found or does not exist.
• 500 Internal Server Error Error message in response body.
• 504 Gateway Timeout Error message in response body.

Headers

Response Headers

Example

Request

DELETE https://us.api.concursolutions.com/budget/v4/fiscalYear/a11cfc7c-967f-415f-9b30-23f8ce2dbf69
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: eb7cf20a-3481-45a5-808c-98b8ef7fe805

Fiscal Year - Schema

Get a FiscalYear

Get a - FiscalPeriod

Budget v4 - Error Response

Budget v4 - Error Message

Response Headers

• concur-correlationid is a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
• RFC 7231 Allow
• RFC 7234 Cache-Control
• RFC 7230 Content-Length
• RFC 7231 Content-Type
• RFC 7231 Date
• RFC 7234 Expires
• RFC 7232 ETag
• RFC 7234 Pragma
• RFC 7231 Server
• RFC 7231 Vary

Budget v4 - Budget Category

Menu

• Getting Started
• Fiscal Year
• Budget Category
• Budget Item
• Budget Tracking Field
• Budget Adjustments

This resource is used to retrieve and update budget categories which are collections of expense types used for budget matching. Each budget item header may have one Budget Category. If it does, only line items with expense types contained in that Budget Category will be accumulated to the budget.

• GET All Budget Categories
• GET a Budget Category
• POST a Budget Category
• DELETE a Budget Category
• GET All Valid Expense Types
• Schema
  • Budget Category
  • Expense Type
  • Error Response
  • Error Message
• Response Headers

GET All Budget Categories

Retrieve a list of all budget categories.

Scopes

This API call requires one of the following scopes:

• budgetitem.read - Refer to Scope Usage for full details.
• budgetitem.write - Refer to Scope Usage for full details.

Request

URI

GET /budget/v4/budgetCategory

Template

Parameters

N/A

Headers

• RFC 7235 Authorization
• RFC 7231 Content-Type

Response

Status Codes

• 200 OK Successful call, response is in body.
• 400 Bad Request The request was determined to be invalid by the server.
• 403 Forbidden The user does not have the necessary permissions to perform the request.
• 500 Internal Server Error Error message in response body.
• 504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Budget Category

Example

GET https://us.api.concursolutions.com/budget/v4/budgetCategory
Authorization: Bearer {token}
Content-Type: application/json

Request

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1292
concur-correlationid: 9d59b6f0-e5bd-47bf-bcad-4c3de9f5c45c

Response

[
    {
      "name":"Marketing and Outreach",
      "description":null,
      "statusType":"OPEN",
      "id":"36047f6c-6cf6-443d-a952-39efb012acdb",
      "expenseTypes":[
        {
          "featureTypeCode":"PURCHASE_REQUEST",
          "expenseTypeCode":"MKTG",
          "id":"f35827a8-7981-4a5b-bfc3-da7ebb4665ff",
          "name":null
        },
        {
          "featureTypeCode":"EXPENSE",
          "expenseTypeCode":"SEMNR",
          "id":"30f16783-e50e-4ab4-b6fb-f66cc75956f2",
          "name":null
        },
        {
          "featureTypeCode":"PURCHASE_REQUEST",
          "expenseTypeCode":"ADVT",
          "id":"64a04928-37b0-49c8-99e8-c346e6d47825",
          "name":null
        }
      ]
    },
    {
      "name":"Airfare",
      "description":null,
      "statusType":"OPEN",
      "id":"459fe79a-9b1e-4ea0-8416-19de0ff14eef",
      "expenseTypes":[
        {
          "featureTypeCode":"EXPENSE",
          "expenseTypeCode":"AIRFR",
          "id":"53300041-3fb9-4a93-8cdf-327fcbe74a0c",
          "name":null
        },
        {
          "featureTypeCode":"REQUEST",
          "expenseTypeCode":"AIRFR",
          "id":"29278c5a-624a-4dd6-a2c1-02dd233d3fbf",
          "name":null
        }
      ]
    }     
]

GET a Budget Category

Retreive the details of a single budget category.

Scopes

This API call requires one of the following scopes:

• budgetitem.read - Refer to Scope Usage for full details.
• budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

GET  /budget/v4/budgetCategory/{id}

Parameters

Headers

• RFC 7235 Authorization
• RFC 7231 Content-Type

Response

Status Codes

• 200 OK Successful call, response is in body.
• 400 Bad Request The request was determined to be invalid by the server.
• 403 Forbidden The user does not have the necessary permissions to perform the request.
• 404 Not Found The resource could not be found or does not exist.
• 500 Internal Server Error Error message in response body.
• 504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Budget Category

Example

GET https://us.api.concursolutions.com/budget/v4/budgetCategory/36047f6c-6cf6-443d-a952-39efb012acdb
Authorization: Bearer {token}
Content-Type: application/json

Request

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 642
concur-correlationid: f7b1a193-46cc-4784-9c6f-d8e1e47ecaa1

Response

{
  "name":"Marketing and Outreach",
  "description":null,
  "statusType":"OPEN",
  "id":"36047f6c-6cf6-443d-a952-39efb012acdb",
  "expenseTypes":[
    {
      "featureTypeCode":"PURCHASE_REQUEST",
      "expenseTypeCode":"MKTG",
      "id":"f35827a8-7981-4a5b-bfc3-da7ebb4665ff",
      "name":null
    },
    {
      "featureTypeCode":"EXPENSE",
      "expenseTypeCode":"SEMNR",
      "id":"30f16783-e50e-4ab4-b6fb-f66cc75956f2",
      "name":null
    },
    {
      "featureTypeCode":"PURCHASE_REQUEST",
      "expenseTypeCode":"ADVT",
      "id":"64a04928-37b0-49c8-99e8-c346e6d47825",
      "name":null
    }
  ]
}

POST a Budget Category

Save a new budget category or update an existing budget category.

• When adding expense types to a budget category, only the feature type code and expense type code are needed.
• Since Expense Report expense types are shared with Request and Payment Request (Invoice) expense types are shared with Purchase Request, only EXPENSE and PAYMENT_REQUEST expense types must be supplied. The types will be copied to REQUEST and PURCHASE REQUEST automatically.
• If an expense type is supplied but the feature is not enabled, it will have no effect. For example, an Invoice-Maintenance expense type can be added to a Budget Category if Invoice is not enabled for Budget--it will not change how spending is assigned to budgets.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

POST  /budget/v4/budgetCategory

Parameters

N/A

Headers

• RFC 7235 Authorization
• RFC 7231 Content-Type

Payload

Budget Category

Response

Status Codes

• 200 OK Successful call, response is in body.
• 400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
• 403 Forbidden The user does not have the necessary permissions to perform the request.
• 404 Not Found The resource could not be found or does not exist.
• 500 Internal Server Error Error message in response body.
• 504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Budget Category or Error Response

Example

POST https://us.api.concursolutions.com/budget/v4/budgetCategory
Authorization: Bearer {token}
Content-Type: application/json

Request

{
  "name": "Advertising Category",
  "description": "Advertising",
  "expenseTypes": [
    {
      "featureTypeCode": "EXPENSE",
      "expenseTypeCode": "ADVT"
    },
    {
      "featureTypeCode": "PAYMENT_REQUEST",
      "expenseTypeCode": "ADVT"
    }
  ],
  "statusType": "OPEN"
}

Response

Success Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 5c00e59f-d00c-4019-8d3d-47130d8e37b4

{
  "name": "Advertising Category",
  "description": "Advertising",
  "id": "d9fd5191-7016-4f50-a6c8-4770bddc01d8",
  "statusType": "OPEN",
  "expenseTypes": [
    {
      "id": "e1dd44da-25b4-4180-8d89-00f3a8d8cf4e",
      "featureTypeCode": "EXPENSE",
      "expenseTypeCode": "ADVT",
      "name": null
    },
    {
      "id": "67253ac1-77e0-4d61-a478-0d194611b320",
      "featureTypeCode": "PAYMENT_REQUEST",
      "expenseTypeCode": "ADVT",
      "name": null
    }
  ]
}

Failure Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 338
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: 44adb686-a624-4ee5-b618-e4ea31a95bec

{
  "status" : false,
  "errorMessageList" : [
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_CATEGORY_NAME_REQUIRED",
      "errorMessage" : "Budget category name is required"
    },
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_CATEGORY_NAME_UNIQUE_ERROR",
      "errorMessage" : "Budget category must have a unique name"
    }
  ]
}

DELETE a Budget Category

Delete a budget category. Budget categories that are in use by budget items may not be deleted.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

DELETE  /budget/v4/budgetCategory/{id}

Template

Parameters

Headers

• RFC 7235 Authorization
• RFC 7231 Content-Type

Response

Status Codes

• 200 OK Successful call, response is in body.
• 400 Bad Request The request was determined to be invalid by the server.
• 403 Forbidden The user does not have the necessary permissions to perform the request.
• 404 Not Found The resource could not be found or does not exist.
• 500 Internal Server Error Error message in response body.
• 504 Gateway Timeout Error message in response body.

Headers

Response Headers

Example

Request

DELETE https://us.api.concursolutions.com/budget/v4/budgetCategory/a5e00b3f-b941-4522-8b0e-07412fb2cc7c
Authorization: Bearer {token}
Content-Type: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 0
concur-correlationid: 39216840-2808-4c49-8874-e9862d96fdb6

GET All Valid Expense Types

Retrieve a list of all possible expense types that may be used in a budget category.

• The list for REQUEST expense types is identical to the list for EXPENSE expense types and similarly PURCHASE_REQUEST is identical to PAYMENT_REQUEST. Due to response size and performance concerns, only EXPENSE and PAYMENT_REQUEST are returned and the caller should assume that identical expense types exist for REQUEST and PURCHASE_REQUEST.

Scopes

This API call requires one of the following scopes:

• budgetitem.read - Refer to Scope Usage for full details.
• budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

GET  /budget/v4/budgetCategory/expenseTypes

Parameters

N/A

Headers

• RFC 7235 Authorization
• RFC 7231 Content-Type

Response

Status Codes

• 200 OK Successful call, response is in body.
• 400 Bad Request The request was determined to be invalid by the server.
• 403 Forbidden The user does not have the necessary permissions to perform the request.
• 500 Internal Server Error Error message in response body.
• 504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Expense Type

Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetCategory/expenseTypes
Authorization: Bearer {token}
Accept: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 367
concur-correlationid: 7afa7091-bc4e-4408-8248-a67f9e24a023

[
  {
    "featureTypeCode":"EXPENSE",
    "expenseTypeCode":"AIRFR",
    "id":null,
    "name":"Airfare"
  },
  {
    "featureTypeCode":"EXPENSE",
    "expenseTypeCode":"AIRTX",
    "id":null,
    "name":"Airfare Ticket Tax"
  },
  {
    "featureTypeCode":"PAYMENT_REQUEST",
    "expenseTypeCode":"CATER",
    "id":null,
    "name":"Catering"
  }
]

Budget Category - Schema

BudgetCategory

ExpenseType

Budget Category - Error Response

Budget Category - Error Message

Budget Category - Response Headers

• concur-correlationid is a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
• RFC 7231 Allow
• RFC 7234 Cache-Control
• RFC 7230 Content-Length
• RFC 7231 Content-Type
• RFC 7231 Date
• RFC 7234 Expires
• RFC 7232 ETag
• RFC 7234 Pragma
• RFC 7231 Server
• RFC 7231 Vary

Budget v4 - Budget Item

Menu

• Getting Started
• Fiscal Year
• Budget Category
• Budget Item
• Budget Tracking Field
• Budget Adjustments

Budget Item

This resource is used to retrieve and update information about a budget that spans a single fiscal year. Each budget has multiple details that correspond to fiscal periods - months, quarters, or a single period for a yearly budget.

• GET All Budget Items
• GET a Budget Item
• POST a Budget Item
• DELETE a Budget Item
• Schema
  • Budget Item Header List
  • Budget Item Header
  • Budget Item Detail
  • Budget Amounts
  • Budget Person
  • Budget Category
  • Expense Type
  • Budget Tracking Value
  • Budget Item Balance
  • Fiscal Year
  • Fiscal Period
  • Date Range
  • Budget Item Response
  • Error Response
  • Error Message
• Response Headers

GET All Budget Items

Retrieve all budget items in groups of up to 50 items. Due to response size and performance considerations, this endpoint does not return budgetItemDetails. Use the GET a Budget Item to retrieve all the details for a single budget.

Scopes

This API call requires one of the following scopes:

• budgetitem.read - Refer to Scope Usage for full details.
• budgetitem.write - Refer to Scope Usage for full details.

Request

URI

GET /budget/v4/budgetItemHeader

Template

Parameters

Headers

• RFC 7235 Authorization
• RFC 7231 Content-Type

Response

Status Codes

• 200 OK Successful call, response is in body.
• 400 Bad Request The request was determined to be invalid by the server.
• 403 Forbidden The user does not have the necessary permissions to perform the request.
• 500 Internal Server Error Error message in response body.
• 504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Budget Item Header List

Example

GET https://us.api.concursolutions.com/budget/v4/budgetItemHeader
Authorization: Bearer {token}
Accept: application/json

Request

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: dd6cee88-b725-4c06-9ee9-0ca4ae4f16b2

Response

{
  "totalRows":122,"offset":0,"limit":50,
  "budgetItemHeaders":[
    {
        "name":"Marketing-US-Jean Normandy",
        "isTest":false,
        "budgetItemStatusType":"OPEN",
        "description":"Marketing-US",
        "id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "costObjects":[
         {
          "code": "6",
          "fieldDefinitionId": "86eee673-3d81-49c2-966a-b63c7a9302e2",
          "value": "2",
          "listKey": "1334",
          "operator": "EQUAL",
          "displayName": "Country Code"
        }
        ],
        "periodType":"YEARLY",
        "active":true,
        "owned":false,
        "budgetAmounts":{
          "pendingAmount":1178.37697091,
          "unExpensedAmount":2310.73578092,
          "spendAmount":35.78378912,
          "adjustedBudgetAmount": 0,
          "availableAmount":8785.83923997,
          "unExpensedSettings":null,
          "threshold":"UNDER",
          "consumedPercent":12
        },
        "createdDate": "2019-06-26T17:49:53.102Z",
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "annualBudget":10000.00000000,
        "budgetCategory":{
          "name":"airfare",
          "description":null,
          "statusType":"OPEN",
          "id":"27451c2d-9121-44bd-b4b0-f2119d2071c7"
        },
        "owner":{
          "externalUserCUUID":"8002250890004822936",
          "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
          "id":"f779261d-77ce-4123-b739-d842ef6f104d",
          "name":"Jean Normandy",
          "email":"jean.normandy@xyz.com",
          "employeeId":"jean.normandy"
         },
        "budgetApprovers":[
          {
            "externalUserCUUID":"8002250890004822936",
            "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
            "id":"f779261d-77ce-4123-b739-d842ef6f104d",
            "name":"Jean Normandy",
            "email":"jean.normandy@xyz.com",
            "employeeId":"jean.normandy"
          }
        ],
        "budgetManagers":[
          {
            "externalUserCUUID":"1563846384638464842",
            "employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
            "id":"e2bae688-e000-464a-8728-e1362c94f172",
            "name":"Walter Gupta",
            "email":"walter.gupta@xyz.com",
            "employeeId":"walter.gupta"
          }
        ],
        "budgetType": "PERSONAL_USE",
        "budgetViewers":[
          {
            "externalUserCUUID":"5005380230004873464",
            "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
            "id":"7ce7dfe0-6168-4b93-bb35-386bf023acc6",
            "name":"Dan Lee",
            "email":"dan.lee@xyz.com",
            "employeeId":"dan.lee"
          }
        ],
        "dateRange": null,
        "fiscalYear":{
          "name":"2017",
          "displayName":"2017",
          "startDate":"2017-01-01",
          "endDate":"2017-12-31",
          "status":"OPEN",
          "id":"a4f9d57f-14ac-4f03-b5aa-4256e5cff790",
          "lastModified":"2017-03-26 20:53:19",
          "currentYear":false
        }
      },
    {"Additional budget item headers removed for brevity":"Additional budget items headers removed for brevity"}
  ],
  "href":"https://us.api.concursolutions.com/budget/v1.1/budgetItemHeader/?offset=0",
  "next":{
    "href":"http://budget-service-rqa3-budget.us-west-2.nonprod.cnqr.delivery/budget/v1.1/budgetItemHeader/?adminView=true&offset=50"
  },
  "previous":null
}